home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / utilities / misc / iffed_v1.01.lha / iffed.doc < prev    next >
Encoding:
Text File  |  1994-11-13  |  21.4 KB  |  628 lines
  1.  
  2.            *********************************************************
  3.  
  4.                                 IFF Editor V1.01
  5.  
  6.                         Written by Alexis WILKE (c) 1994
  7.  
  8.            *********************************************************
  9.  
  10.  
  11.  
  12.                                       ***
  13.  
  14.      SUMMARY
  15.  
  16.   1.  INTRODUCTION
  17.   2.  INSTALLATION
  18.   3.  GETTING STARTED
  19.   4.  EDIT A FILE
  20.   4.1  THE BUTTONS
  21.   4.2  THE MENU
  22.   5.  EDIT A CHUNK
  23.   6.  CHUNK STRUCTURES
  24.   7.  KNOWN BUGS
  25.   8.  COPYRIGHTS
  26.   9.  ABOUT MY OTHER PRODUCTS
  27.  10.  CONTACTS
  28.  
  29.  
  30.  
  31.                                       ***
  32.  
  33.      1. INTRODUCTION
  34.  
  35.  
  36.   This tool was created because while making a new file format, one must usually
  37. change  it  often.  This editor allows the user to edit and adjust the file data
  38. easily, without complex programming which would result in lost time.
  39.  
  40.  
  41.  
  42.                                       ***
  43.  
  44.      2. INSTALLATION
  45.  
  46.  
  47.   To  install the IFF Editor, copy the file 'iffed' into a directory which is in
  48. your  list  of  PATHs  and  the file 'iff.stc' into 'S:'.  The file 'iff.stc' is
  49. optional,  but when missing, you are prompted.  The file 'iff.stc' can be copied
  50. in your current directory only (i.e.  if you want to test this tool).  Note that
  51. IFFEd checks the current directory first.
  52.  
  53.  
  54.                                       ***
  55.  
  56.      3. GETTING STARTED
  57.  
  58.  
  59.   The use is very interface-like.  The tool can be loaded from the Workbench, or
  60. from  your  CLI like most tools I create.  The data file 'iff.stc' contains some
  61. known  chunk  structure  definition.   All  those  structures can be modified by
  62. anyone.  New releases will probably contain more structures.  The structures are
  63. declared  mostly  like in C language.  Below, you will see the definition of the
  64. available instructions and specific keywords or names.
  65.  
  66.  
  67.   To  load the file, you can select the IFF file icon on your Workbench and then
  68. double  click  on  IFFEd.   Alternately,  from  the  CLI  you  can  type  'IFFEd
  69. <filename>'.  (A file requester will appear if you start IFFEd without file name
  70. or  selected  icon.)  Only one file can be edited at a time.  At any moment, you
  71. can  load a new file by clicking on the 'Load New File' button.  Clicking on the
  72. 'New'  button  from  the  file requester will allow you to create a new IFF file
  73. from  nothing.   The  file  name will have to be supplied later, also you do not
  74. have to bother naming the file if you decide to click 'New'.
  75.  
  76.  
  77.  
  78.                                       ***
  79.  
  80.      4. EDIT A FILE
  81.  
  82.  
  83.   After you started IFFEd, you automatically are editing the file.  At this time
  84. the following options are available to you:
  85.  
  86.  
  87.  
  88.      4.1  THE BUTTONS
  89.  
  90.  
  91.       . New
  92.  
  93.           (Note: Not the 'New' button from the file requester)
  94.  
  95.           Creates  a  new  chunk.  The  chunk will be empty and will receive the
  96.         name '???'.  The new chunk is inserted before the current selection.  If
  97.         there is no selection, the new chunk is appended at the end.
  98.  
  99.  
  100.       . Del
  101.  
  102.           Deletes  the  selected  chunk.  The chunk can be restored by:
  103.  
  104.            o the 'Undo All' button if it was in the original file
  105.            o 'Undo' -> 'All Possible Hunks' menu item if it was new
  106.  
  107.  
  108.       . Undo
  109.  
  110.           When  not  disabled,  the  currently  selected chunk has been modified
  111.         from the original file, or is a new chunk.  New chunks can't be undone.
  112.  
  113.           So,  a click on the "Undo" button will restore the chunk to the way it
  114.         was  last saved.  Changes made after saving don't enter the undo buffer,
  115.         and clicking "Undo" returns the chunk to its last saved condition.
  116.  
  117.  
  118.       . Edit
  119.  
  120.           Enables  you  to  edit  the selected chunk for you to modify it as you
  121.         wish.  For more information about editing a chunk, see EDIT A CHUNK.
  122.  
  123.  
  124.       . Size display and Valid acknowledge
  125.  
  126.           When  you  select  a  new  chunk from the list, the actual size of the
  127.         chunk  is displayed in the box at the bottom of the window.  Then if the
  128.         chunk is "known" (if it as been defined in the 'iff.stc' file,) the text
  129.         "Valid"  or  "Bd Size"  appear  on  the  right of the list.  Note that a
  130.         structure  with  a  variable size will usually display "Bd Size," but it
  131.         does not mean the chunk is invalid.
  132.  
  133.  
  134.       . IFF Type
  135.  
  136.           The  IFF  type  definition  is also found into the 'iff.stc' file.  If
  137.         IFFEd is able to find a definition which fits the file contains, then it
  138.         will be displayed.  For instance, ILBM is defined as "Picture."
  139.  
  140.  
  141.       . IFF Name
  142.  
  143.           This  text  box editor enables you to modify the name of the IFF file.
  144.         This  is the name defined at the very beginning of the file like:  ILBM,
  145.         8SVX, CTLG...
  146.  
  147.  
  148.       . Undo All
  149.  
  150.           Restores all chunks as present into the original file.  The new chunks
  151.         will be deleted and the others will be restored with their original size
  152.         and data. You should not apply "Undo All" on a new file, because nothing
  153.         is original.
  154.  
  155.  
  156.       . Save
  157.  
  158.           Saves  the file with current information.  A file name will have to be
  159.         supplied if a new file has been created.  If you need to modify the name
  160.         of the file before to save it, use the "Save as ..." from the menu.
  161.  
  162.  
  163.       . Load New File
  164.  
  165.           As mentioned before, this button will enable you to load another file.
  166.         If the active file has been modified, you will be prompted about whether
  167.         you want to save the file or forget all the modifications.
  168.  
  169.  
  170.       . Quit (or the Close Window button)
  171.  
  172.           This button will make you quit the IFFEd tool.
  173.  
  174.  
  175.  
  176.      4.1  THE MENU
  177.  
  178.  
  179.   The  menu  is hidden from you.  You have to click on the right mouse button to
  180. make  it  appear.  The menu uses layers and is also very quick, but this usually
  181. results  in  a bad refresh of the other windows.  To have a refresh, just move a
  182. window  (Note:   this  is one more hidden function which has not been defined in
  183. intuition.library!!!) However any other tasks can be running at the same time on
  184. the Workbench.
  185.  To select a menu item, move the mouse as usual.  Menus which have an arrow (->)
  186. have  sub-menus.  You  will  have  to wait up to two seconds for the sub-menu to
  187. appear.  A description of each menu item follows:
  188.  
  189.  
  190.       . Menu: About
  191.  
  192.           Displays a little window with the copyright and version of IFFEd.
  193.  
  194.  
  195.       . Menu: Load new file
  196.  
  197.           This is an equivalent of the "Load New File" button.
  198.  
  199.  
  200.       . Menu: Save
  201.  
  202.           This is an equivalent of the "Save" button.
  203.  
  204.  
  205.       . Menu: Save as ...
  206.  
  207.           This is also explained in the "Save as" button. It enables you to save
  208.         your file with a different name. The file requester is displayed for you
  209.         to defined the new name.
  210.  
  211.  
  212.       . Menu: Structures -> Print
  213.  
  214.           This menu item will print all structures into the output.  This may not
  215.         work  if  you use the Workbench.  It should be use only by people wishing
  216.         to edit the 'iff.stc' file.  It is useless for anyone else.
  217.  
  218.  
  219.       . Menu: Structures -> 'int' type is 4 bytes
  220.  
  221.           The  type 'int' in C might be 2 or 4 bytes.  By default it is set to 2
  222.         bytes.  However if you use structures with 4 bytes integers, select this
  223.         menu  item.  A  check  mark appear which let you know you use four bytes
  224.         integers.
  225.  
  226.           Select it again to restore the size of 2 bytes.
  227.  
  228.  
  229.       . Menu: Quit
  230.  
  231.           This is an equivalent of the "Quit" button.
  232.  
  233.  
  234.       . Menu: Chunk ...
  235.  
  236.           Each  point under 'Chunk' is just a copy of the button presents on the
  237.         right of the chunk list.
  238.  
  239.  
  240.       . Menu: Undo All -> Original file
  241.  
  242.           This is an equivalent of the "Undo All" button.
  243.  
  244.  
  245.       . Menu: Undo All -> All possible chunks
  246.  
  247.           This  is  explained  under the "Undo All" button.  It will restore the
  248.         data  and  size of all chunks.  All deleted chunks are restored as well,
  249.         new or not.
  250.  
  251.  
  252.  
  253.                                       ***
  254.  
  255.      5. EDIT A CHUNK
  256.  
  257.   You will have the "Edit Chunk Data" window opened when a chunk is selected and
  258. the  "Edit"  button  is  clicked.  The edit window has the following buttons and
  259. functions:
  260.  
  261.       . The list
  262.  
  263.           Chunk  data  will  appear  in the list box.  If a structure definition
  264.         exists from the "iff.stc" file, then the name (and size when available,)
  265.         of  that structure are displayed on the first line, then the fields will
  266.         follow  on  next  lines.   If  the chunk data buffer is smaller than the
  267.         structure,  a line will be inserted at the end of the list to inform you
  268.         about  the  problem.   Then  you can redefine the size with the "Resize"
  269.         button.   If  the size is larger than the structure the last fields will
  270.         be inserted with a different color.
  271.  
  272.           If  you  are  missing a chunk definition, you will have to quit IFFEd,
  273.         edit  the  file  'iff.stc' to add the definition and then restart IFFEd.
  274.         IFFEd  loads  the  definitions  when  it  starts  and  will  not know if
  275.         'iff.stc' has been modified while you are using it.
  276.  
  277.           When  a  structure  is not defined, the default internal definition is
  278.         used instead:
  279.  
  280.                        char  *ary[8];
  281.  
  282.  
  283.       . Field Edit Box
  284.  
  285.           Click  on  a  line  from  the list to edit its contents.  The data are
  286.         copied  into  the  field  box  under  the list.  When several values are
  287.         defined on the same line, each must be separated with a space and should
  288.         be  supllied.   If  more  values than necessary are defined the last are
  289.         ignored.   If  less  values than necessary are supplied, the last values
  290.         are  supposedly  null  and  the  end of the buffer will be cleared.  The
  291.         parser  understands  decimal,  hexadecimal,  binary  and  octal  values.
  292.         Decimcal values must contain only digits (0-9).  Hexadecimal are defined
  293.         with  digits  (0-9) and letters (A-F,) to force a hexadecimal value, the
  294.         sign  '$'  should  preceed the value or an H should follow the value.  A
  295.         value  is  also recognized as hexadecimal if it contains a letter (A-F),
  296.         however  "B" may generate confusion.  The binary value must start with a
  297.         sign  '%' or finish with a B if it is at the end.  The octal values will
  298.         finish  with  an  O.   The parser is case insensitive, so letters may be
  299.         typed in lower case.
  300.  
  301.  
  302.       . Chunk Name Edit Box
  303.  
  304.           The  chunk  name  is defined at the top-right of the "Edit Chunk Data"
  305.         window.   If  you  modify  it,  the list will be modified to reflect the
  306.         correct  structure  (if  such  a  structure  exists.) A null name is not
  307.         valid.
  308.  
  309.  
  310.       . Use Button
  311.  
  312.           Click  on  this  button  when you are done.  The modifications will be
  313.         saved  and the chunk will be noted as modified.  You will not be able to
  314.         click  on  the  "Use"  button  if  no  name  is  supplied  for the chunk
  315.         (available in the edit box at the top-right corner.) If no modifications
  316.         have  been  made, a click on "Use" is equivalent to a click on "Cancel".
  317.         The keys Shift-Return can be used instead.
  318.  
  319.  
  320.       . Size Box and Resize Button
  321.  
  322.           The  size  box  shows  you  the  current  size  of  the chunk.  If the
  323.         structure  of  chunk  is  defined,  then expected size will be displayed
  324.         between  parentheses  and in a special color.  If it is not the size you
  325.         wanted, click on the "Resize" button and type the new desired size.
  326.  
  327.  
  328.       . Cancel (and the Close Window button)
  329.  
  330.          This  button  will  close the "Edit Chunk Data" window and forget about
  331.         any  modification.  You  should  use this button if you were editing the
  332.         chunk just to have a look at it.
  333.  
  334.  
  335.  
  336.                                       ***
  337.  
  338.      6. CHUNK STRUCTURES
  339.  
  340.  
  341.   The  following  is the language description for the 'iff.stc' file.  The basic
  342. definition  is  like  C.   An  'iff.stc' file is given with this tool as example
  343. (??and  first  start).  There are no restriction about the size of the 'iff.stc'
  344. file.
  345.  
  346.   The structure file actually contains 4 different types of definitions:
  347.  
  348.  
  349.       . typedef       (generates new types)
  350.  
  351.           The  'typedef'  instruction can be used to generate new types and then
  352.         avoid  the  definition  of  a  'complex'  type  repeatedly.  There is an
  353.         example of typedef:
  354.  
  355.                  typedef unsigned char     uchar;
  356.                  typedef unsigned short    ushort;
  357.                  typedef unsigned int      uint;
  358.                  typedef unsigned long     ulong;
  359.  
  360.  
  361.       . struct        (generates user types)
  362.  
  363.           The  structures  (which  may  contain structures as necessary) will be
  364.         used to define user defined types.  There is an example for BitMapHeader
  365.         structure:
  366.  
  367.                  struct BitMapHeader {
  368.                      ushort    width;
  369.                      ushort    height;
  370.                      ushort    xPos;
  371.                      ushort    yPos;
  372.                      uchar     nPlanes;
  373.                      uchar     masking;
  374.                      uchar     compression;
  375.                      char      PAD;
  376.                      short     transparentColor;
  377.                      uchar     xAspect;
  378.                      uchar     yAspect;
  379.                      ushort    pageWidth;
  380.                      ushort    pageHeight;
  381.                  };
  382.  
  383.         or with multiple structure definitions:
  384.  
  385.                  struct Point {
  386.                      short     x;
  387.                      short     y;
  388.                  };
  389.  
  390.                  struct BitMapHeader {
  391.                      struct Point  size;
  392.                      struct Point  pos;
  393.                      uchar     nPlanes;
  394.                      uchar     masking;
  395.                      uchar     compression;
  396.                      char      PAD;
  397.                      short     transparentColor;
  398.                      uchar     xAspect;
  399.                      uchar     yAspect;
  400.                      struct Point  pageSize;
  401.                  };
  402.  
  403.  
  404.       . type          (defines IFF type names)
  405.  
  406.           The  IFF file types are defined like variables that receive a value (a
  407.         string  pointer.) Those definitions have to start with the type 'char *'
  408.         or  an  equivalent  'typedef,'  have  the name of the IFF type to define
  409.         (Like  ILBM, 8SVX, MAP, ...) and be followed by the string.  The special
  410.         type  '????' is by default used as the unknown type.  Here is an example
  411.         for the ILBM type:
  412.  
  413.                  char *ILBM = "Picture";
  414.  
  415.  
  416.       . variable      (defines the relation between the chunk and the data)
  417.  
  418.           The variables define the link between an IFF file type and the name of
  419.         a  chunk.   They should not have a value assigned to them.  When a chunk
  420.         can be found in any IFF file, you can define the IFF type as '*'.  There
  421.         are  two examples, the BitMapHeader is a chunk specific to the ILBM type
  422.         and the BODY is found is most files containing one block of data:
  423.  
  424.                  struct BitMapHeader     *ILBMBMHD;
  425.                  char                    "*BODY"[];
  426.  
  427.           As  you  can  see,  both  variables  are  pointers.   It is necessary;
  428.         otherwise  an  error  will  be  generated.   The  BODY definition is set
  429.         between  quotes  to  be  sure  that  the  '*' is part of the name, not a
  430.         pointer  sign.   Note that a name which contains very special characters
  431.         or  which  starts with a digit will be defined between quotes ("8SVX" or
  432.         "(c) " are two examples).
  433.  
  434.           If  you  have  several  IFF files types which are very similar and you
  435.         want all of them to know about a chunk.  You may use the sign '?' rather
  436.         than a specific letter.  For instance if you had 'MAP0' and 'MAP1' which
  437.         both have a chunk named 'GDIR' the following can be used:
  438.  
  439.                  char                    *"MAP?GDIR";
  440.  
  441.           The  use  of a single pointer (defined by '*') and the use of an array
  442.         (defined by '[]') defines one occurance of the given type, or any number
  443.         of  occurance  of  the  given  type  respectively.  A specific number of
  444.         occurance can as well be defined with [<value>].
  445.  
  446.  
  447.   The  following  is  a  complete  definition  of the language.  This definition
  448. includes a special syntax:
  449.  
  450.      [ ... ]     optional informations
  451.      < ... >     refer to a rule
  452.      { ... }     repeat as many times as necessary
  453.      '?'         you must type the character(s) ? in your file
  454.  
  455.  
  456.  
  457.       . basic types             (referenced as: <type>)
  458.  
  459.          Byte  Type  Definition(s)
  460.          Size
  461.  
  462.            1    I  'char', 'signed char'
  463.            1    I  'unsigned char'
  464.            2    I  'short', 'signed short', 'short int', 'signed short int'
  465.            2    I  'unsigned short', 'unsigned short int'
  466.           2/4   I  'int', 'signed int'
  467.           2/4   I  'unsigned int'
  468.            4    I  'long', 'signed long', 'long int', 'signed long int'
  469.            4    I  'unsigned long', 'unsigned long int'
  470.            4    F  'float', 'signed float'
  471.            8    F  'double', 'signed double', 'long float', 'signed long float'
  472.            0    S  'void'
  473.  
  474.           I- integer, F- float, S- special
  475.  
  476.  
  477.       . typedef definition      (the <identifier> becomes a <type>)
  478.  
  479.            'typedef' <type>     <identifier> {',' <identifier>} ';'
  480.  
  481.  
  482.       . structure definition    ('struct' <name> becomes a <type>)
  483.  
  484.            'struct' <name> '{'
  485.                { <type>      <identifier> {',' <identifier> } ';' }
  486.                { <int type>  <identifier> ':' <value>
  487.                                           {',' <identifier> ':' <value> } ';' }
  488.            '};'
  489.  
  490.           Note: field definitions are not yet supported.
  491.  
  492.           Because a structure is a type by itself it can be used anywhere a type
  493.         is required (in a 'typedef' or a 'struct' definition for instance.)
  494.  
  495.  
  496.       . the variables
  497.  
  498.            <type>    <identifier> [ '=' '"' <string> '"' ]
  499.                             { ',' <identifier> [ '=' '"' <string> '"' ] } ';'
  500.  
  501.  
  502.       . a string                (referenced as: <string>)
  503.  
  504.         a string is a list of any character defined between " and ".
  505.  
  506.  
  507.       . an identifier           (referenced as: <identifier>)
  508.  
  509.           An  identifier is a list of character, it can include any letter (case
  510.         sensitive)  and  digits.   However  it  can't  start  with a digit.  The
  511.         characters '@', '_' and '?' can be defined within an identifier.
  512.  
  513.           If  you need to use anything which is forbidden as previously defined,
  514.         you can define the identifier between " and " like in "8SVX" or "(c) ".
  515.  
  516.  
  517.  
  518.                                       ***
  519.  
  520.      7. KNOWN BUGS
  521.  
  522.  
  523.   I  know  there are some bugs into my interface handler which is only linked to
  524. the IFF editor code itself. I still have a hard time to be able to find out were
  525. the bugs are. One of those bugs is when you double click on a chunk name to edit
  526. that chunk, the list remains active and may appear into the new opened window.
  527.  
  528.  
  529.  
  530.                                       ***
  531.  
  532.      8. COPYRIGHTS
  533.  
  534.  
  535.   This product is a copyright of Alexis WILKE.
  536.  
  537.  
  538.   This  program  is  a FreeWare, however donations and post cards are welcome at
  539. (tell me which tool(s) you've got from my production):
  540.  
  541.       Alexis WILKE
  542.       1511, S.W. Park Ave #615
  543.       Portland, OR 97201
  544.            U.S.A.
  545.  
  546.  
  547.   This  program  is  protected by the law of Copyrights.  His author is the only
  548. one to have the right to decide if this tool can be sold.  No authorization will
  549. be given until a written consent has been signed by Alexis WILKE.
  550.  
  551.  
  552.  
  553.                                       ***
  554.  
  555.      9. ABOUT MY OTHER PRODUCTS
  556.  
  557.  
  558.   There is a list of my other products:
  559.  
  560.  
  561.      . Overdrive
  562.  
  563.           When  I  first came in America, I praticipated to the elaboration of a
  564.         game  named 'Overdrive'.  This game uses three disks and is available on
  565.         request (address your request to me.)
  566.  
  567.                ftp.cdrom.com:/pub/aminet/game/demo/Overdrive2.lha
  568.                ftp.cdrom.com:/pub/aminet/game/demo/Overdrive2.readme
  569.  
  570.  
  571.      . lk
  572.  
  573.           lk  is a powerful linker, with no bugs.  It will replace your very old
  574.         SLINK  6.5  and  after you tried it, you will not even think about BLINK
  575.         any  version or ALINK.  The last version of DICE as changed a lot and it
  576.         is not garanteed that lk will be able to link 'dcc' object files.
  577.  
  578.           This tool is a shareware ($15) and a free demo version is available on
  579.         your AmiNET:
  580.  
  581.                ftp.cdrom.com:/pub/aminet/dev/misc/LK_V1.??.lha
  582.                ftp.cdrom.com:/pub/aminet/dev/misc/LK_V1.??.readme
  583.  
  584.  
  585.      . make
  586.  
  587.           I  wrote  my  own  make,  because  assemblers  does not come with file
  588.         makers,  this  wasn't  a  bad  idea.   This make is very similar to make
  589.         available on Unix machines.
  590.  
  591.           This tool is a freeware and can be found on your AmiNET:
  592.  
  593.                ftp.cdrom.com:/pub/aminet/dev/c/amake_v1.??.lha
  594.                ftp.cdrom.com:/pub/aminet/dev/c/amake_v1.??.readme
  595.  
  596.  
  597.      . IFF Editor
  598.  
  599.           IFF  Editor  is  also  on  your  AmiNET.  If you want to take the last
  600.         version of it you can search for it:
  601.  
  602.                ftp.cdrom.com:/pub/aminet/util/edit/iffed_v1.??.lha
  603.                ftp.cdrom.com:/pub/aminet/util/edit/iffed_v1.??.readme
  604.  
  605.  
  606.  
  607.                                       ***
  608.  
  609.     10. CONTACTS
  610.  
  611.  
  612.   If  you  need some help for anything that you can't firgue out alone or if you
  613. have comments and suggestions, all are welcome at:
  614.  
  615.           alexis@netcom.com
  616.  
  617.   or at:
  618.  
  619.           Alexis WILKE
  620.           1511, S.W. Park Avenue #615
  621.           Portland, OR 97201
  622.               U.S.A
  623.  
  624.           Phone: (503) 248-5607
  625.  
  626.  
  627.            *********************************************************
  628.